package edu.mercer.sse.tlocal;

import com.google.common.cache.CacheStats;

/**
 * Thread Object Proxification : Object Proxy for thread-specific storage.<p>
 * 
 * Parameterized type-safe through use of generics I, X:<p>
 * 
 * <ul>
 * <li> I - Index of stored thread-global object instance; i.e., "Results"
 * <li> X - Type of thread-global object; i.e., StringBuilder
 * </ul>
 * 
 * Summary:<p>
 * 
 * Demonstrate thread-specific storage pattern variant where one type of
 * 	object permitted in cache per thread.<p>
 * 
 *  Multiple object instances for the one object type permitted 
 *  per thread. Mapped by key of type generic I.<p>
 * 
 * Detail:<p>
 * 
 * Thread Object Proxification: collections of multiple object states per 
 *  thread.<p>
 * 
 * To simplify garbage collection and concurrency, Guava object cache used for 
 * 	storing each 'Thread Object Proxification' instance.<p>
 * 
 * Guava object cache created as static/Singleton. Contains each such 
 * 	object-state collection for all threads. Mapping key is the thread state 
 * 	in the Guava cache-of-caches.<p>
 * 
 * Each thread may have its own 'Thread Object Proxification' instance.<p>
 *  
 * Factory usage limits one such new instance per object type created,
 * 	per thread.<p>
 *
 * @see <a href="http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/cache/Cache.html">
 * 	Cache</a>
 * @see CacheStats
 */

public interface ThreadObjectProxification<I extends Object, 
										   X extends Object>
{
	/**
	 * Getter for generic object type X.<p>
	 * 
	 * Retrieves thread-global object instance.<p>
	 * 
	 * Retrieve instance mapped by generic key/index of I.<p>
	 * 
	 * @param objectIndex - Generic I for object index/key
	 * 
	 * @see ThreadObjectProxification
	 */
	
	X get( final I objectIndex );
	
	
	/**
	 * Setter for generic object type X.<p>
	 * 
	 * Places thread-global object instance into collection.<p>
	 * 
	 * Sets instance map using generic key/index of I.<p>
	 * 
	 * @param objectIndex - Generic I for object index/key
	 * @param objectInstance - Generic X for object instance
	 * 
	 * @return  this
	 * 
	 * @see ThreadObjectProxification
	 */
	
	ThreadObjectProxification<I, X> set( final I objectIndex, 
										 final X objectInstance );


	/**
	 * Setter-Append for generic object type X.<p>
	 * 
	 * Sets or appends instance for map entry using generic key/index of I.<p>
	 * 
	 * Appends thread-global object instance into collection. Existing 
	 * 	instance if any is added:<p>
	 * 
	 * For numeric Integer, Double:<p>
	 * 
	 * -> Sum placed into collection. If no existing entry, works as 
	 * 'set' method. Addition of existing entry from left to right, adding 
	 * 	new instance to existing.<p>
	 * 
	 * For Strings:<p>
	 * 
	 * -> Concatenation occurs from left to right, adding new instance to 
	 * 	existing.<p>
	 * 
	 * <u>Types supported</u>: Integer, Double, String, StringBuilder.<p>
	 * 
	 * @param objectIndex - Generic I for object index/key
	 * @param objectInstance - Generic X for object instance
	 * 
	 * @return  this
	 * 
	 * @see #set(Object, Object)
	 * 
	 * @see ThreadObjectProxification
	 */
	
	ThreadObjectProxification<I, X> append( final I objectIndex, 
										 	final X objectInstance );

	
	/**
	 * Get CacheStats for Guava Object cache defined as Singleton for all 
	 * 	threads.<p>
	 * 
	 * Use to monitor cache additions, evictions as threads execute.<p>
	 * 
	 * @return  CacheStats Statistics object for the Cache&#60;I,X&#62; Guava 
	 * 	object cache-of-caches 
	 * 
	 * @see CacheStats
	 */
	
	CacheStats getCacheStats();
	
	
}//interface
